/*
 * $Id: QEExchangeResolver.h 248 2008-09-08 15:31:38Z jon $
 * Sleeper
 *
 * Created by Jon Gordon on 7/24/08
 * Copyright Jon Gordon.  All rights reserved.
 * 
 * Permission is hereby granted, free of charge, to any person obtaining 
 * a copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including 
 * without limitation the rights to use, copy, modify, merge, publish, 
 * distribute, sublicense, and/or sell copies of the Software, and to 
 * permit persons to whom the Software is furnished to do so, subject to 
 * the following conditions:
 * 
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 
 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */


#import <Cocoa/Cocoa.h>

#import "QETokenizer.h"

//
// Model class, attempts to resolve a string that represents a possible
// November Sweepstakes exchange into the elements of such an exchange.
//
// Author: $Author: jon@bway.net $
// Version: $Revision: 2 $
//
@interface QEExchangeResolver : NSObject {
@private
    BOOL exchangeValid;
    NSDictionary *elements;
    NSDictionary *resolvedElements;
    NSDictionary *sourceTokens;
    QETokenizer  *tokenizer;
} // QEExchangeResolver

//
// Default initializer.
//
- (QEExchangeResolver *)init;

//
// Attempts to match the input exchange to the known exchange elements.
//
// parameters:
//  inputExchange - string that is to be parsed and evaluated
//
// return:
//  YES if the parts of the input string can be matched 1 to 1 with the
//  elements, NO otherwise
//
- (BOOL)resolveExchange:(NSString *)inputExchange;

//
// Indicates whether the current exchange is valid.
//
// return:
//  YES if the exchange includes only legal exchange elements and includes
//  all required elements, NO otherwise
//
- (BOOL)isExchangeValid;

//
// Returns the elements recognized in the current exchange.
//
// return:
//  NSDictionary with one entry for each resolved element, in which
//  the element name is the key, and an object representing the
//  resolved value for that element is the value
- (NSDictionary *)resolvedElements;

//
// Given one of the element values, such as was obtained through a prior
// call to resolvedElements:, returns the source token that represents
// this element.
//
// parameter:
//  resolvedElement - NSObject representing an element value
//
// return:
//  NSString containing source token, from most recently entered
//  exchange, that corresponds to resolvedElement
- (NSString *)sourceTokenForResolvedElement:(id)resolvedElement;

//
// Gets an array listing the names of the elements in an exchange, in the
// they are expected to be received in.
//
// return:
//  names of the exchange elements
//
+ (NSArray *)elementNames;

@end
